home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / program / xmsbcp11.zip / DESCRIPT.TXT next >
Text File  |  1997-04-13  |  13KB  |  367 lines
  1.  
  2.  
  3.  
  4.  
  5.     XMSBCP
  6.     XMS Interface for Borland C/C++ and Borland Pascal
  7.     Version 1.1
  8.  
  9.     Developed by Tanescu A. Horatiu
  10.     April 1997
  11.  
  12.  
  13.     Short description of constants/types/variables/functions
  14.  
  15.  
  16. ─────────────────────────────────────────────────────────────────
  17.     Constants
  18. ─────────────────────────────────────────────────────────────────
  19.  
  20. XMS ERROR CODES:
  21.  
  22.  XE_NOERROR        0x00  no error, successful operation
  23.  
  24.  XE_NOTIMPLEMENTED    0x80  the function is not implemented
  25.  XE_VDISK        0x81  a VDISK device is detected
  26.  XE_A20            0x82  an A20 error occurs
  27.  XE_DRVFAULT        0x8E  a general driver error occurs
  28.  XE_UNRECOVERABLE    0x8F  an unrecoverable driver error occurs
  29.  
  30.  XE_NO_HMA        0x90  the HMA does not exist
  31.  XE_NO_FREEHMA        0x91  the HMA is already in use
  32.  XE_BAD_HMAMINSIZE    0x92  DX is less than the /HMAMIN= parameter
  33.  XE_HMANOTALLOCATED    0x93  the HMA is not allocated
  34.  XE_A20ENABLED        0x94  the A20 line is still enabled
  35.  
  36.  XE_NO_FREEMEM        0xA0  all extended memory is allocated
  37.  XE_NO_FREEHANDLES    0xA1  all available extended memory handles are in use
  38.  XE_BAD_HANDLE         0xA2  the handle is invalid
  39.  XE_BAD_SRC_HANDLE    0xA3  the SourceHandle is invalid
  40.  XE_BAD_SRC_OFF        0xA4  the SourceOffset is invalid
  41.  XE_BAD_DEST_HANDLE    0xA5  the DestHandle is invalid
  42.  XE_BAD_DEST_OFF    0xA6  the DestOffset is invalid
  43.  XE_BAD_LEN        0xA7  the Length is invalid
  44.  XE_BAD_OVERLAP        0xA8  the move has an invalid overlap
  45.  XE_PARITY        0xA9  a parity error occurs
  46.  XE_UNLOCKED        0xAA  the block is not locked
  47.  XE_LOCKED        0xAB  the block is locked
  48.  XE_LOCKCOUNTOF        0xAC  the block's lock count overflows
  49.  XE_LOCKFAIL        0xAD  the lock fails
  50.  
  51.  XE_UMB2BIG        0xB0  a smaller UMB is available
  52.  XE_NO_UMBS        0xB1  no UMBs are available
  53.  XE_BAD_UMBSEG        0xB2  the UMB segment number is invalid
  54.  
  55.  
  56. Miscellaneous constants
  57.  
  58.  HMASEG            0xFFFF High Memory Area (HMA) Segment
  59.  HMASTARTOFF        0x0010 HMA Starting Offset
  60.  HMAENDOFF        0xFFFF HMA Ending Offset
  61.  
  62.  
  63. ─────────────────────────────────────────────────────────────────
  64.     Types
  65. ─────────────────────────────────────────────────────────────────
  66.  
  67. - 16-bit handle to an extended memory block.
  68.  
  69.   C:
  70.   typedef unsigned int xmhandle;
  71.  
  72.   PASCAL:
  73.   type
  74.     XMHandle = Word;
  75.  
  76.   This type is used by extended memory blocks (EMBs) handling functions.
  77.  
  78.  
  79. - Structure (record) used by the generic memory transfer routine
  80.   (xmemcpy/XMemCopy).
  81.  
  82.   C:
  83.   typedef struct {
  84.     unsigned long xmc_count;
  85.     xmhandle      xmc_srchandle;
  86.     unsigned long xmc_srcoff;
  87.     xmhandle      xmc_desthandle;
  88.     unsigned long xmc_destoff;
  89.   } xmemcpy_t;
  90.  
  91.   PASCAL:
  92.   type
  93.     TXMCopyRec = record
  94.       Count        : Longint;
  95.       SourceHandle : XMHandle;
  96.       SourceOff    : Longint;
  97.       DestHandle   : XMHandle;
  98.       DestOff      : Longint;
  99.     end;
  100.  
  101.  
  102. ─────────────────────────────────────────────────────────────────
  103.     Variables
  104. ─────────────────────────────────────────────────────────────────
  105.  
  106. - Error status variable
  107.  
  108.   C:
  109.   unsigned char xmserrno;
  110.  
  111.   PASCAL:
  112.   var
  113.     XMSError : Byte;
  114.  
  115.   All the functions from this library (except the initialization functions)
  116.   change this variable to reflect the status of the last XMS operation.
  117.   See also the XMS Error Codes Constants.
  118.  
  119.  
  120. - Indicator of the existence of an XMS driver
  121.  
  122.   C:
  123.   unsigned char xmsinstalled;
  124.  
  125.   PASCAL:
  126.   var
  127.     XMSInstalled : Boolean;
  128.  
  129.   Set to 1 (TRUE) by the initialization function if an XMS driver is
  130.   found, otherwise set to 0 (FALSE).
  131.  
  132.  
  133. ─────────────────────────────────────────────────────────────────
  134.     Initialization Functions
  135. ─────────────────────────────────────────────────────────────────
  136.  
  137. C:    int _xmsdrivercheck(void);
  138. PASCAL: function XMSDriverCheck : Boolean;
  139.  
  140.     Determines if an XMS driver is installed.
  141.  
  142. C:    void _getxmsfunct(void);
  143. PASCAL: procedure GetXMSFunct;
  144.  
  145.     Returns the address of the XMS driver's control function.
  146.  
  147. C:    int initxms(void);
  148. PASCAL: procedure InitXMS;
  149.  
  150.     Inits the XMS library.
  151.     MUST BE CALLED BEFORE ANY OTHER ROUTINE!
  152.  
  153. > For C users:
  154.     If an XMS driver is found, xmsinstalled is set to 1, otherwise is
  155.     set to 0.
  156.     Initxms is automatically called when you include xms.h (a #pragma
  157.     startup initxms directive is placed in xms.h).
  158.  
  159. > For Pascal users:
  160.     If an XMS driver is found, XMSInstalled is set to True, otherwise is
  161.     set to False.
  162.     InitXMS is automatically called when you use xms.tpu (XMSInit is
  163.     called in the initialization part of the xms unit).
  164.  
  165. ─────────────────────────────────────────────────────────────────
  166.     Driver Information Functions
  167. ─────────────────────────────────────────────────────────────────
  168.  
  169. C:    unsigned int xmsver(void);
  170. PASCAL:    function XMSVersion : Word;
  171.  
  172.     Returns the XMS driver version number. If the result is 300 then
  173.     the version is 3.00.
  174.  
  175. C:    unsigned int xmsverinfo(unsigned int* revision, int* HMA);
  176. PASCAL:    function XMSVersionInfo(var Revision : Word; var HMA : Boolean) : Word;
  177.  
  178.     Returns the XMS driver version number and internal revision number
  179.     and query the existence of HMA.
  180.  
  181.  
  182.  
  183. NOTE:    the following routines return an error code in xmserrno (C) or in
  184.     XMSError (PASCAL). If the significance of the return value is not
  185.     specified in the description of the routine it is assumed that it
  186.         returns a non-zero value (in C) / True (in Pascal) on success and
  187.         a zero value (in C) / False (in Pascal) on error.
  188.  
  189.  
  190. ─────────────────────────────────────────────────────────────────
  191.     High Memory Area (HMA) Management Functions
  192. ─────────────────────────────────────────────────────────────────
  193.  
  194. C:    int hmarequest(unsigned int reqsize);
  195. PASCAL:    function HMARequest(ReqSize : Word) : Boolean;
  196.  
  197.     Attempts to reserve the high memory area to the caller. Reqsize
  198.     contains the bytes which are needed (up to 65520 bytes). If an
  199.     application fails to release the HMA before it terminates, the HMA
  200.     becomes unavailable to the other programs until the system is
  201.     restarted.
  202.  
  203. C:    int hmarelease(void);
  204. PASCAL:    function HMARelease : Boolean;
  205.  
  206.     Releases the high memory area and allows other programs to use it.
  207.  
  208. ─────────────────────────────────────────────────────────────────
  209.     A20 Management Functions
  210. ─────────────────────────────────────────────────────────────────
  211.  
  212. C:    int globalenableA20(void);
  213. PASCAL:    function GlobalEnableA20 : Boolean;
  214.  
  215. C:    int globaldisableA20(void);
  216. PASCAL:    function GlobalDisableA20 : Boolean;
  217.  
  218. C:    int localenableA20(void);
  219. PASCAL:    function LocalEnableA20 : Boolean;
  220.  
  221. C:    int localdisableA20(void);
  222. PASCAL:    function LocalDisableA20 : Boolean;
  223.  
  224. C:    int queryA20(void);
  225. PASCAL:    function QueryA20 : Boolean;
  226.  
  227.         Refer to the XMS specification for information.
  228.  
  229. ─────────────────────────────────────────────────────────────────
  230.     eXtended Memory Management Functions
  231. ─────────────────────────────────────────────────────────────────
  232.  
  233. C:    unsigned int xmfreespace(void);
  234. PASCAL:    function XMFreeSpace : Word;
  235.  
  236.     Returns the amount of free extended memory in K-bytes.
  237.  
  238. C:    unsigned int xmcontig(void);
  239. PASCAL:    function XMContig : Word;
  240.  
  241.     Returns the size of the largest free extended memory block in
  242.     K-bytes.
  243.  
  244. C:    xmhandle xmalloc(unsigned int size);
  245. PASCAL:    function XMAlloc(Size : Word) : XMHandle;
  246.  
  247.     Allocates an extended memory block and returns a handler which is
  248.     used by the other extended memory routines to refer to this block.
  249.         If the allocation fails, the returned handle is null. Size is in
  250.     K-bytes.
  251.  
  252. C:    int xmfree(xmhandle hxmem);
  253. PASCAL:    function XMFree(Handle : XMHandle) : Boolean;
  254.  
  255.     Frees an extended memory block previously allocated using xmalloc.
  256.     If a program fails to release the allocated extended memory before
  257.     it terminates, the memory becomes unavailable to other programs until
  258.     the system is restarted. Locked blocks can't be freed.
  259.  
  260. C:    unsigned long xmlock(xmhandle hxmem);
  261. PASCAL:    function XMLock(Handle : XMHandle) : Longint;
  262.  
  263.     Locks an extended memory block and returns its base address as a
  264.     32-bit linear address. Locked memory blocks are guaranteed not to
  265.     move.
  266.  
  267. C:    int xmunlock(xmhandle hxmem);
  268. PASCAL:    function XMUnlock(Handle : XMHandle) : Boolean;
  269.  
  270.     Unlocks a locked extended memory block. Any 32-bit pointers to the
  271.     block become invalid and should not be used.
  272.  
  273. C:    int xmhandleinfo(xmhandle hxmem, unsigned int* size, unsigned char* lockcount, unsigned char* freehandles);
  274. PASCAL:    function XMHandleInfo(Handle : XMHandle; var Size : Word; var LockCount, FreeHandles : Byte) : Boolean;
  275.  
  276.     Returns additional information about an extended memory block: the
  277.         size in K-bytes and the number of locks. Freehandles is the number
  278.     of free handlers which are available.
  279.  
  280. C:    int xmrealloc(xmhandle hxmem, unsigned int newsize);
  281. PASCAL:    function XMRealloc(Handle : XMHandle; NewSize : Word) : Boolean;
  282.  
  283.     Reallocates a previously allocated extended memory block. Locked
  284.     blocks can't be resized. Size is in K-bytes.
  285.  
  286. ─────────────────────────────────────────────────────────────────
  287.     eXtended Memory Transfer Functions
  288. ─────────────────────────────────────────────────────────────────
  289.  
  290. VERY IMPORTANT NOTE:    For each of the following transfer functions the size
  291.             (in bytes) of the transferred block must be EVEN!
  292.  
  293. C:    int xmemcpy(xmemcpy_t *x);
  294. PASCAL: function XMemCopy(const CopyRec : TXMCopyRec) : Boolean;
  295.  
  296.     Transfers an extended memory block (generic function).
  297.  
  298. C:    int _xmemcpy(unsigned long n, xmhandle srchandle, unsigned long srcoff, xmhandle desthandle, unsigned long destoff);
  299. PASCAL:    function _XMemCopy(N : Longint; SrcHandle : XMHandle; SrcOff : Longint; DestHandle : XMHandle; DestOff : Longint) : Boolean;
  300.  
  301.     Transfers an extended memory block (generic function). In C/C++ it is
  302.         used by the following 4 functions. In Pascal is provided for
  303.         compatibility with the C/C++ version.
  304.  
  305. C:    int ctoxm(xmhandle desthandle, unsigned long destoff, void far *src, unsigned long n);
  306. PASCAL:    function CopyCMemToXMem(DestHandle : XMHandle; DestOff : Longint; Src : Pointer; N : Longint) : Boolean;
  307.  
  308.     Transfers a block from conventional to extended memory. The size (in
  309.     bytes) of the transferred block (n) must be even.
  310.  
  311. C:    int xmtoc(void far *dest, xmhandle srchandle, unsigned long srcoff, unsigned long n);
  312. PASCAL:    function CopyXMemToCMem(Dest : Pointer; SrcHandle : XMHandle; SrcOff : Longint; N : Longint) : Boolean;
  313.  
  314.     Transfers a block from extended to conventional memory. The size (in
  315.     bytes) of the transferred block (n) must be even.
  316.  
  317. C:    int xmtoxm(xmhandle desthandle, unsigned long destoff, xmhandle srchandle, unsigned long srcoff, unsigned long n);
  318. PASCAL:    function CopyXMem(DestHandle : XMHandle; DestOff : Longint; SrcHandle : XMHandle; SrcOff : Longint; N : Longint) : Boolean;
  319.  
  320.     Transfers a block within extended memory. The size (in bytes) of the
  321.     transferred block (n) must be even.
  322.  
  323. C:    int ctoc(void far *dest, void far *src, unsigned long n);
  324. PASCAL:    function CopyMem(Dest : Pointer; Src : Pointer; N : Longint) : Boolean;
  325.  
  326.     Transfers a block within conventional memory. The size (in bytes) of
  327.     the transferred block (n) must be even.
  328.  
  329. ─────────────────────────────────────────────────────────────────
  330.     Upper Memory Blocks (UMB) Management Functions
  331. ─────────────────────────────────────────────────────────────────
  332.  
  333. C:    unsigned int umballoc(unsigned int* size);
  334. PASCAL:    function UMBAlloc(var Size : Word) : Word;
  335.  
  336.     Attempts to allocate an upper memory block of the specified size in
  337.     paragraphs. On success the function returns the segment base of the
  338.     allocated block and size contains the actual size of the allocated
  339.     block in paragraphs. On error, the function returns 0 and the size
  340.     of the largest free UMB is returned in size.
  341.  
  342. C:    int umbfree(unsigned int umbseg);
  343. PASCAL:    function UMBFree(UMBSeg : Word) : Boolean;
  344.  
  345.     Frees a previously allocated upper memory block.
  346.  
  347. C:    int umbrealloc(unsigned int umbseg, unsigned int* size);
  348. PASCAL:    function UMBReAlloc(UMBSeg : Word; var Size : Word) : Boolean;
  349.  
  350.     Reallocates an upper memory block to a newly specified size. Size
  351.         is in paragraphs.
  352.  
  353. ─────────────────────────────────────────────────────────────────
  354.     XMS error functions
  355. ─────────────────────────────────────────────────────────────────
  356.  
  357. C:    char* xmserrormsg(int errorcode);
  358. PASCAL:    function XMSErrorMsg(ErrorCode : Byte) : string;
  359.  
  360.     Returns the description of an XMS error message.
  361.  
  362. C:    void pxmserror(const char *s);
  363. PASCAL:    procedure PrintXMSError(const S : string);
  364.  
  365.     Prints (in C on stderr) the description of the last XMS error that
  366.     occured, followed by ":" and by the user string (S).
  367.